import { Meta, Status, Props, Story } from '../../../../.storybook/components';
import * as Stories from './PhoneNumberInput.stories';

<Meta of={Stories} />

# PhoneNumberInput

<Status variant="stable" />

The PhoneNumberInput component provides a straightforward way for users to type their phone number in an accurate, consistent format including the country code and subscriber number.

<Story of={Stories.Base} />
<Props />

## Usage

When you need to collect a phone number from the user. This could be for contact information, two-factor authentication, or other purposes where a phone number is required.
The component allows the user to select their country code, and normalizes the input to the [E.164 format](https://www.itu.int/rec/t-rec-e.164/en).

## Validations

Use the `validationHint` prop to communicate the expected response to users.

### Invalid

When the user needs to change the value to proceed. This could be due to an incorrect format or an unsupported country code.
The state can be applied to the entire component or only to a specific field, e.g. in the example below is used to indicate that only the subscriber number is not valid

### Warning

When the user is recommended to change the value, but can proceed without doing so. Use it when the provided value could have unintended side-effects, such as a high cost for international calls.

### Valid

When the user is reassured that the value is valid. Use sparingly, as the PhoneNumberInput component does not validate that the number is actually in service.

<Story of={Stories.Validations} />

## Readonly

Use the `readOnly` prop to indicate that the field is not currently editable. This can be useful in situations where the user needs to view but not edit the phone number, such as in a summary or review screen. The state can be applied to the entire component or only to a specific field, e.g. in the example below is used to indicate that only the country code is read-only.

<Story of={Stories.Readonly} />

## Optional

Use the `optionalLabel` prop to indicate that the field is optional. This can help reduce the cognitive load for the user by clearly indicating which fields are required and which are not. This label is only displayed when the `required` prop is falsy.

<Story of={Stories.Optional} />

## Disabled

You should use only when the value is a critical information from the user that we already have and we do not want the user to edit it easily. A disabled field should only be open for editing again if a user event is triggered.

<Story of={Stories.Disabled} />

## With Prefix

Use the `renderPrefix` prop to add a small prefix to the country code selected input field. By default, the component will display the selected country's [Flag](Components/Flag/Docs). You can override that behavior by providing your own prefix component.

<Story of={Stories.WithPrefix} />
